Zum Hauptinhalt springen

Ereignisse

Pro IVR veröffentlicht während jedes Anrufs im Sprachmenü Ereignisse („FpEvents"): eines bei jeder aufgelösten Zielauswahl (IvrSelectionEvent) und eines, wenn das Gespräch endet, während es sich noch im Menü befindet (IvrHangupEvent). Die Nutzlast enthält Anrufer, angerufene Nummer, die Eingaben und die durchlaufenen Menüstufen — die Grundlage für Menü-Analytik (etwa mit Insight Analytics), CRM-Anreicherung und Automatisierung über EventBridge oder eigene STARFACE-Module.

Verwendung durch Dritte

Diese Schnittstelle ist für die Nutzung durch Drittsysteme freigegeben. Änderungen und Erweiterungen werden je Version in den Release Notes dokumentiert.

Grundlagen​

  • Typ: FpEvents — der modulübergreifende Ereignismechanismus der Fluxpunkt-Module auf dem anlageninternen Ereignisbus. Es handelt sich um keine Netzwerkschnittstelle: Nach außen gelangen die Ereignisse über EventBridge, zum Beispiel als Webhook, E-Mail, Syslog-Meldung oder Datenbankeintrag.
  • Ereignisnamen: IvrSelectionEvent und IvrHangupEvent. Beim Abonnieren wirkt ein abschließendes * als Platzhalter — Ivr* abonniert beide Pro-IVR-Ereignisse.
  • Nutzlast: ein JSON-Objekt. Felder ohne Wert entfallen in der Nutzlast; unbekannte Felder werden beim Empfang ignoriert.
  • Zugriff: EventBridge abonniert Ereignisse per Konfiguration. Eigene Module verwenden die Modulfunktion FpEvent abonnieren (FpRegisterEvents) — Download und Anleitung im Artikel Schnittstellen & APIs. Insight Analytics konsumiert beide Ereignisse ab Werk und wertet damit die Sprachmenü-Abläufe aus.
  • Zuverlässigkeit: Fire-and-forget ohne Empfangsbestätigung. Fehler beim Veröffentlichen beeinträchtigen den Anruf nicht (Eintrag im Modul-Log).
  • Verfügbar seit: Modulversion 26.7.13.

IvrSelectionEvent​

Pro IVR veröffentlicht IvrSelectionEvent bei jeder aufgelösten Zielauswahl, unmittelbar bevor das Ziel ausgeführt wird. Eine Auswahl entsteht durch eine DTMF-Eingabe, das Ergebnis einer Datenbankprüfung (SQL-Check), die Zuordnung des KI-Voice-Bots oder das Ausweichziel einer Stufe. Auch Sprünge zwischen Stufen sind Auswahlen: Ein Anruf, der drei Menüstufen durchläuft, erzeugt mehrere Ereignisse. Ob eine Auswahl die finale war, erkennen Sie daran, dass ivrSelectedTarget keine Stufen-Referenz (step:<uuid>) ist.

FeldTypBedeutung
moduleInstanceIdStringUUID der Modulkonfiguration (Instanz), die den Anruf verarbeitet hat.
moduleInstanceNameStringAnzeigename der Modulkonfiguration.
timestampZahlZeitpunkt der Zielauswahl in Millisekunden seit dem 1. 1. 1970 (UTC).
callerNameStringName des Anrufers, sofern bekannt; sonst leer.
callerNumberStringRufnummer des Anrufers — die externe Rufnummer, ersatzweise die interne Nebenstelle; bei anonymen Anrufern leer oder anonymous.
calledNumberStringUrsprünglich angerufene Nummer (die der Modulkonfiguration zugeordnete Service-Rufnummer).
ivrPressedDigitsStringEingabe-Kette über alle bisher durchlaufenen Stufen, Stufen durch ; getrennt: DTMF-Ziffern bzw. das vom KI-Voice-Bot gewählte Stichwort (z. B. 1;Support;42#). Leer, wenn noch keine Eingabe erfolgte.
ivrSelectedTargetStringDas gewählte Ziel, wie konfiguriert: Stufen-Sprung step:<uuid>, Rufnummer bzw. Legacy-Syntax (100, Support[100], Zentrale<*9123>, *9123) oder callback: (Rückrufbitte).
ivrVisitedStepsArray von ObjektenKette der bislang durchlaufenen Stufen in Besuchsreihenfolge; das letzte Element ist die Stufe, in der die Auswahl getroffen wurde.

Jedes Objekt in ivrVisitedSteps besteht aus zwei Feldern:

FeldTypBedeutung
stepIdStringStabile UUID der Stufe — bleibt beim Umbenennen erhalten.
stepNameStringName der Stufe zum Ereigniszeitpunkt.
IvrSelectionEvent — finale Zielauswahl nach zwei Menüstufen
{
  "moduleInstanceId": "b1f6d2c4-8e37-4a5b-9c02-5d7e13a9f6b8",
  "moduleInstanceName": "Zentrale IVR",
  "timestamp": 1785571200000,
  "callerName": "Erika Musterfrau",
  "callerNumber": "+4972112345678",
  "calledNumber": "+4972187654300",
  "ivrPressedDigits": "1;2",
  "ivrSelectedTarget": "Technik[201]",
  "ivrVisitedSteps": [
    { "stepId": "7c2a9d14-53f6-4e0b-8a77-1d2f3c4b5a69", "stepName": "Hauptmenü" },
    { "stepId": "e4b8c1f0-9a2d-4c6e-b357-8f1a0d9c2e46", "stepName": "Support" }
  ]
}

IvrHangupEvent​

Pro IVR veröffentlicht IvrHangupEvent, wenn das Gespräch endet, während sich der Rufablauf noch im Sprachmenü befindet — also ohne finale Weiterleitung an eine Rufnummer oder Voicemail und ohne abgeschlossene Rückrufbitte. Das Feld reason unterscheidet, ob der Anrufer aufgelegt oder das Modul das Gespräch beendet hat. Eingaben, die der Anrufer unmittelbar vor dem Auflegen noch gemacht hat, sind in ivrPressedDigits enthalten.

FeldTypBedeutung
moduleInstanceIdStringUUID der Modulkonfiguration (Instanz), die den Anruf verarbeitet hat.
moduleInstanceNameStringAnzeigename der Modulkonfiguration.
timestampZahlZeitpunkt des Gesprächsendes in Millisekunden seit dem 1. 1. 1970 (UTC).
callerNameStringName des Anrufers, sofern bekannt; sonst leer.
callerNumberStringRufnummer des Anrufers — die externe Rufnummer, ersatzweise die interne Nebenstelle; bei anonymen Anrufern leer oder anonymous.
calledNumberStringUrsprünglich angerufene Nummer (die der Modulkonfiguration zugeordnete Service-Rufnummer).
reasonStringGrund des Gesprächsendes — einer der Werte aus der folgenden Tabelle.
hangupStepIdStringUUID der Stufe, in der das Gespräch endete.
hangupStepNameStringName der Stufe, in der das Gespräch endete.
ivrPressedDigitsStringEingabe-Kette bis zum Auflegen, Stufen durch ; getrennt: DTMF-Ziffern bzw. vom KI-Voice-Bot gewählte Stichworte.
ivrVisitedStepsArray von ObjektenKette der durchlaufenen Stufen in Besuchsreihenfolge (stepId, stepName — siehe IvrSelectionEvent); das letzte Element ist die Stufe des Auflegens.

reason nimmt einen der folgenden Werte an:

WertBedeutung
CALLER_HANGUPDer Anrufer hat innerhalb einer Stufe aufgelegt.
NO_TARGETKeine zuordenbare Eingabe bzw. Entscheidung und kein Ausweichziel — das Modul beendet das Gespräch.
LOOP_LIMITDie maximal zulässige Anzahl an Stufenwechseln je Anruf wurde überschritten (Schleifenschutz).
INVALID_TARGETDas konfigurierte Ziel ist ungültig oder die referenzierte Stufe existiert nicht (mehr).
IvrHangupEvent — Anrufer legt im Untermenü auf
{
  "moduleInstanceId": "b1f6d2c4-8e37-4a5b-9c02-5d7e13a9f6b8",
  "moduleInstanceName": "Zentrale IVR",
  "timestamp": 1785571260000,
  "callerName": "Erika Musterfrau",
  "callerNumber": "+4972112345678",
  "calledNumber": "+4972187654300",
  "reason": "CALLER_HANGUP",
  "hangupStepId": "e4b8c1f0-9a2d-4c6e-b357-8f1a0d9c2e46",
  "hangupStepName": "Support",
  "ivrPressedDigits": "1",
  "ivrVisitedSteps": [
    { "stepId": "7c2a9d14-53f6-4e0b-8a77-1d2f3c4b5a69", "stepName": "Hauptmenü" },
    { "stepId": "e4b8c1f0-9a2d-4c6e-b357-8f1a0d9c2e46", "stepName": "Support" }
  ]
}
Anwendungsbeispiel

Ein Kunde möchte Menü-Abbrüche nachfassen: EventBridge abonniert IvrHangupEvent und ruft bei reason = CALLER_HANGUP einen Webhook des CRM auf. Aus callerNumber und hangupStepName entsteht automatisch eine Rückruf-Aufgabe — inklusive der Stufe, in der der Anrufer aufgegeben hat.

Versionierung & Kompatibilität​

Ereignisnamen und Feldnamen sind stabile Verträge; Erweiterungen erfolgen additiv (neue Ereignisse, neue optionale Felder). Verarbeiten Sie Nutzlasten daher tolerant gegenüber zusätzlichen Feldern. Das Feld reason des IvrHangupEvent ist seit Modulversion 26.7.23 enthalten; Version 26.7.13 sendet das Ereignis noch ohne dieses Feld. Den anlagenweiten Ereigniskatalog führt die Ereignisliste der EventBridge-Dokumentation; Änderungen an den Ereignissen dokumentieren die Release Notes der jeweiligen Modulversion.

Inhaltsverzeichnis